home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2004 #9 / Amiga Plus CD - 2004 - No. 09.iso / amigaplus / tools / amigaos4_only / image2icon / image2icon.doc < prev    next >
Text File  |  2004-08-03  |  11KB  |  265 lines
  1.                     Image2Icon
  2.          © 2000-2004 by Stephan Rupprecht
  3.                 All rights reserved.
  4.     
  5.  
  6. COPYRIGHT AND DISCLAIMER
  7.  Image2Icon is copyrighted 2000-2004 by Stephan Rupprecht.
  8.  All rights reserved. This program is freeware, so no financial  
  9.  donations required. Redistribution allowed if the package is 
  10.  left unchanged except for addition of new language catalogs.   
  11.  The author is not responsible for any damage caused by the 
  12.  use or misuse of this documentation and/or the program(s) it 
  13.  describes.
  14.  
  15.  
  16. REQUIREMENTS
  17.  Any Amiga® (compatible) computer with AmigaOS® 3.x,
  18.  newicon.library (for os3.0/3.1 based systems) and 68020+ cpu.
  19.  
  20.  
  21. DESCRIPTION
  22.  Image2Icon is yet another conversion tool that creates thumbnail
  23.  icons from pictures.
  24.  
  25.  
  26. USAGE
  27.  The program can be started from a shell as well as from wb. The
  28.  following options/tooltypes are provided:
  29.  
  30.  FILE/M,MW=MAXWIDTH/N,MH=MAXHEIGHT/N,C=CROP/S,IA=IGNOREASPECT/S,
  31.  AX=ASPECTX/N/K,AY=ASPECTY/N/K,NI=NEWICON/S,FIP=FREEICONPOS/S,
  32.  FW=FRAMEWIDTH/N/K,FH=FRAMEHEIGHT/N/K,T=TRANSPARENT/S,R=REMAPFS/S,
  33.  OPT=OPTIMIZE/S,FL=FRAMELESS/S,SS=SHOWSIZE/K,F=FONT/K,D=DITHER/S,
  34.  FS=FONTSIZE/N/K,FST=FONTSTYLE/K,AP=APPICON/K,APX=APPICONX/N/K,
  35.  APY=APPICONY/N/K,V42=MODEV42/S,QU=QUALITY/N/K,P=PLANAR/S,
  36.  MP=MAXPEN/N/K,SF=STARTFROM/K,DT=DEFAULTTOOL/K,GS=GREYSCALE/S,
  37.  J=JPEG/K,I=ILBM/K,C=CMAP/K,MD=MAXDEPTH/N/K,ST=STACKSIZE/N/K,
  38.  MWP=MAXWIDTHPERCENT/N/K,MHP=MAXHEIGHTPERCENT/N/K,AG=ADDGLOW/S,
  39.  ABS=ABSOLUTE/S,Q=QUIET/S
  40.  
  41.  FILE/M: the image(s) to convert. If you don't give any, the
  42.   program will add an appicon on which you can drop the pictures
  43.   to convert. By double-clicking the icon the program can be
  44.   terminated.
  45.   
  46.  MW=MAXWIDTH/N,MH=MAXHEIGHT/N: the maximum size of the icon to
  47.   create. Please note that NewIcons are limited to a maximum
  48.   size of 93x93 pixels, os3.5 icons are limited to 256x256 pixels.
  49.  
  50.  MWP=MAXWIDTHPERCENT/N/K,MHP=MAXHEIGHTPERCENT/N/K: the maximum
  51.   size of the icon _in percent_ relative to the workbench screen
  52.   size.
  53.   
  54.  C=CROP/S: disables downscaling.
  55.  
  56.  IA=IGNOREASPECT/S: ignore the screen aspect ratio when scaling
  57.   the image. 
  58.   
  59.  ABS=ABSOLUTE/S: don't aspect scale when the image becomes
  60.   larger than MAXWIDTH or MAXHEIGHT. Use MAXWIDTH and MAXHEIGHT
  61.   as destination size instead.
  62.  
  63.  AX=ASPECTX/N/K,AY=ASPECTY/N/K: allows you to override the
  64.   screen aspect ratio of the workbench screen.
  65.  
  66.  NI=NEWICON/S: create a NewIcon even when os3.5 is available.
  67.   This option does nothing on a os3.0/os3.1 based system.
  68.  
  69.  FIP=FREEICONPOS/S: the resulting icon doesn't have a fixed
  70.   position.
  71.  
  72.  FW=FRAMEWIDTH/N/K,FH=FRAMEHEIGHT/N/K: allows you to add a
  73.   frame around the image.
  74.   
  75.  T=TRANSPARENT/S: by default, the transparent color (if any) of
  76.   an image is ignored. Thus the resulting icon won't have one
  77.   unless this option was specified.
  78.   
  79.  OPT=OPTIMIZE/S: optimize the image data, if possible (os3.5).
  80.   
  81.  FL=FRAMELESS/S: tell workbench not to draw a border around the
  82.   icon (os3.5).
  83.  
  84.  SS=SHOWSIZE/K: display the image size in the icon. The following
  85.   keywords are recognized:
  86.   
  87.   TOPLEFT,TOPRIGHT,CENTER,BOTTOMLEFT,BOTTOMRIGHT
  88.  
  89.  F=FONT/K: the font that is used by SHOWSIZE.
  90.  
  91.  FS=FONTSIZE/N/K: the size of the font.
  92.  
  93.  FST=FONTSTYLE/K: the style of it, either OUTLINE,SHADOW or 
  94.   NORMAL (default)
  95.  
  96.  AP=APPICON/K: the icon to use as appicon.
  97.  
  98.  APX=APPICONX/N/K,APY=APPICONY/N/K: its position on the workbench
  99.   screen. You always need to specify both.
  100.   
  101.  V42=MODEV42/S: when enabled truecolor images will be converted to
  102.   8bit by the picture.datatype and not by Image2Icon (requires
  103.   picture.datatype v44). You can use this option in combination
  104.   with either REMAPFS or DITHER to improve the quality, but you'll
  105.   probably prefer to stay away from this option as it slows down
  106.   the conversion process without improving the result.
  107.  
  108.  QU=QUALITY/N/K: the quality of the dithering algorithm to use:
  109.   
  110.   0 no dithering is done (quick & dirty)
  111.   1 dither with a 16x16 Bayer matrix (default, still quick but not so dirty:)
  112.   2 dto.
  113.   3 Floyd Steinberg (slowest but best quality)
  114.  
  115.  GS=GREYSCALE/S: enables greyscale output.
  116.  
  117.  MP=MAXPENS/N/K: the maximum number of pens/colors to use. If GREYSCALE
  118.   is not enabled, the program will either use 8,12,27,36,64,80,125,150,
  119.   216 or 252 colors depending on which is next nearest number to the one
  120.   you've specified.
  121.   
  122.  MD=MAXDEPTH/N/K: the maximum number of bitplanes to use. I2I translates
  123.   this to MAXPENS.
  124.  
  125.  D=DITHER/S: by default, images with <= 256 colors are remapped to
  126.   their original palette after scaling (ignoring MAXPEN). If you
  127.   enable this option, the images will be dithered instead. This is
  128.   faster but normally results in a thumbnail image with less quality
  129.   as the original palette of the image is not taken into account.
  130.  
  131.  R=REMAPFS/S: by default, images with <= 256 colors are remapped to
  132.   their original palette after scaling (ignoring MAXPEN). If you
  133.   enable this option, the images will also be dithered using Floyd 
  134.   Steinberg dithering.
  135.  
  136.  P=PLANAR/S: this will create an "old style"/planar image in addition
  137.   to the os3.5/NewIcon image.
  138.  
  139.  DT=DEFAULTTOOL/K: the default tool of the icon to create.
  140.  
  141.  SF=STARTFROM/K: how to start the default tool when the user
  142.   double-clicks the icon, this can either be WB, CLI or REXX.
  143.  
  144.  ST=STACKSIZE/N/K: the default stacksize of the icon (>= 4096 bytes).
  145.  
  146.  J=JPEG/K: create a jpeg image instead of an icon. If you specify
  147.   JPEG="" the jpeg image will be saved to the same directory
  148.   where the source also exists, the suffix of the image will be
  149.   changed to "_small.jpg", so that the original image does not get
  150.   overwritten. When the image should be saved to a different directory
  151.   simply specify, eg. JPEG="Pictures:%f_thumb.jpg" where %f will
  152.   be replaced by the file name later.
  153.  
  154.   This option requires jpeg.library by Paul Huxham:
  155.   http://www.scouts.org.au/steeplesoftware
  156.  
  157.  I=ILBM/K: create an ilbm image instead of an icon. Also see
  158.   J=JPEG/K. This option requires picture.datatype v43 or better.
  159.   For 24bit output specify MAXDEPTH=24.
  160.   
  161.  C=CMAP/K: The ilbm file which palette should be used when
  162.   remapping an image. You should also specify REMAPFS for better
  163.   quality. 
  164.   
  165.  AG=ADDGLOW/S: create an icon with a "glowing" alternate image, this
  166.   option overrides the FRAMEWIDTH and FRAMEHEIGHT options.
  167.  
  168.  Q=QUIET/S: supresses any output except error messages.
  169.  
  170.  
  171. KNOWN PROBLEMS
  172.  - the ilbm.datatype that comes with os3.5 doesn't support bw/greyscale
  173.    images produced by BME (PageStream). Please use one of my ilbm.datatypes
  174.    instead (util/dtype/ilbmdt44.lha or util/dtype/ilbmdtPPC.lha).
  175.  - the SHOWSIZE option doesn't work when creating JPEG images or
  176.    24bit ILBMs. This is not supported yet.
  177.  
  178.  
  179. SPECIAL THANKS GO TO
  180.  Olaf Barthel who wrote the dithering code used by this program
  181.  and of course to the people who reported bugs and made suggestions :)
  182.  Also thanks to Dámaso D. Estévez for the spanish doc, Raul Silva for #
  183.  the icons and Frank (Matrix) for the french doc.
  184.  
  185.  
  186. HISTORY
  187.  1.0  first public release
  188.  1.1  added QU=QUALITY/N/K option to select a different dithering
  189.       algorithm. supports HAM images via picture.datatype v44 now.
  190.  1.2  optionally creates a "old style" image in addition to the 
  191.       os3.5/NewIcon one, see PLANAR/S option <John Blyth>. added
  192.       some smoothing code to the scaler, this requires additional
  193.       cpu time but makes the icon look nicer. Please note that I
  194.       had to disable TRANSPARENT/S to make it work correctly. It's
  195.       possible to drop drawers on the appicon, now. This will allow
  196.       you to convert a whole dir in one go.
  197.  1.3  some datatypes pass an aspect ratio of 0:0 causing a division
  198.       by zero guru (0x80000005), fixed. When dropping a drawer on
  199.       the appicon the program will no longer put up an error requester
  200.       when encountering an unsupported filetype <John Blyth>. added
  201.       MP=MAXPENS/N/K option although it isn't quite useful (IMHO).
  202.  1.4  added STARTFROM/K, DEFAULTTOOL/K options <Mario Cattaneo>.
  203.       creating NewIcons on a 3.5 based system didn't work, as NewIcon
  204.       and 3.5 image data was saved to disk.
  205.  1.5  should work on a NewIcons based system finally <Xenomorph>,
  206.       <Rainer M. Herold>.
  207.  1.6  no longer crashs on small images where the source size is the
  208.       same as the destination size.
  209.  1.7  added GS=GREYSCALE/S option <Nick Clover>. If QUIET is not given,
  210.       the program will output some status messages to the current
  211.       console window (when started from WB, the WINDOW tooltype must be
  212.       given to see this messages).
  213.  1.8  added D=DITHER/S,R=REMAPFS/S options. the code to handle EHB pictures
  214.       disappeared somehow, it's now back;) HAM images are supported in-
  215.       dependently from the installed picture.datatype, now. rewrote some
  216.       parts of code to work on chunky buffers instead of bitmaps, this should
  217.       result in a faster thumbnail creation, especially users without an RTG
  218.       software should notice an speed improvement.
  219.  1.9  the dithering code can use upto 252 colors, now (before 216).
  220.  1.10 optimized the scaling code a bit, included some nice icons made by
  221.       Raul Silva.
  222.  1.11 if you start the program from wb or if you drop icons on its appicon,
  223.       a simple gui with a progress bar will be shown.
  224.  1.12 the progress bar was shown even when QUIET was given. unless
  225.       PLANAR was specified the program has caused several enforcer hits when
  226.       a NewIcon was saved on a os3.0/os3.1 based system.
  227.  1.13 remapping works much faster, now. Included WarpOS version.
  228.  1.14 Ooops! The program didn't work when started from wb because it
  229.       waited for the wbmsg twice <Raul Silva>. The WarpUP version is
  230.       a bit faster now as the ppc will be used for scaling and smoothing,
  231.       too (requires more memory!!!).
  232.  1.15 added JPEG/K,ILBM/K,CMAP/K,MD=MAXDEPTH/N/K options. improved matrix
  233.       dithering and removed 4x4 Bayer matrix.
  234.  1.16 there was an old bug in the smoothing code messing around with the
  235.       pixel colors, the WOS version never had this problem <Christian
  236.       Effenberger>. Now displays a proper error message when the CMAP
  237.       couldn't be found. The JPEG/K and ILBM/K allow you to specify a
  238.       destination path, now.
  239.  1.17 implemented ADDGLOW/S,MAXWIDTHPERCENT/N/K,MAXHEIGHTPERCENT/N/K,
  240.       ABS=ABSOLUTE/S options. reimplemented support for images with
  241.       a transparent color.
  242.  1.18 because of a "misplaced" parenthesis, the 68k version could
  243.       allocate a temporary buffer that was a few bytes too small <Greg>.
  244.  1.19 the text in the progress bar appears centered again <Greg>.
  245.  1.20 AmigaOS4 version, to use jpeg.library you need to install the
  246.       supplied jpeg.l.main file in LIBS:
  247.  
  248.  
  249. AUTHOR
  250.  
  251. Please send bug reports and ideas to:
  252.  
  253.  Stephan Rupprecht
  254.  Apfeldweg 1
  255.  D44359 Dortmund
  256.  Germany
  257.  
  258.  Send emails to
  259.  
  260.  info@stephan-rupprecht.de
  261.  
  262.  WWW
  263.  
  264.  http://stephan-rupprecht.de
  265.